package nl.rug.jvleusen.datastructurelib;

import java.util.Collection;
import nl.rug.jvleusen.datastructurelib.set.*;

/**
 * This is the interface for each class implementing a set in this library, 
 * a set being a collection of values wherein each value can appear once.
 * Any implementation should follow the rules of the {@link Collection} 
 * interface, as well as correctly implement the logical set methods as 
 * specified in this interface.
 * 
 * @author Jeroen van Leusen
 * @see DoublyLinkedList
 * @see LinkedList
 * @see MultiSet
 * @see NDimensionalArray
 * @see Set
 */
public interface ISet<E> extends Collection<E> {
    
    /**
     * Returns a new set containing all elements from the specified set and this set.
     * 
     * @param set2 A set with which to take the logical union with this set from.
     * @return A new ISet of the same type as this set, containing the union of this set and set2.
     */
    public ISet<E> union(ISet<E> set2);
    
    /**
     * Returns a new set containing all elements that are containing in the specified set as well as this set.
     * 
     * @param set2 A set with which to take the logical intersection with this set from.
     * @return A new ISet of the same type as this set, containing the intersection of this set and set2.
     */
    public ISet<E> intersection(ISet<E> set2);
    
    /**
     * Returns a new set containing each element that is either in this set or the specified set, but not both.
     * 
     * @param set2 A set with which to take the logical difference with this set from.
     * @return A new ISet of the same type as this set, containing the difference of this set and set2.
     */
    public ISet<E> difference(ISet<E> set2);
    
    /**
     * Returns <tt>true</tt> if this set contains all of the elements in the specified set
     * 
     * @param set2 set to be checked if it is a subset against this set.
     * @return A boolean signifying if set2 is a subset of this set.
     */
    public boolean subset(ISet<E> set2);
}
